SwingOSC -- version 0.59 (built 03-feb-08) --

statement

SwingOSC is an OpenSoundControl (OSC) server intended for scripting Java(tm), such as to create graphical user interfaces with AWT or Swing classes. It uses the reflection and beans mechanism to dynamically create instances of java classes and control them. A separate set of SuperCollider language classes is included to allow the building of GUIs from within sclang. SwingOSC is (C)opyright 2005–2008 by Hanns Holger Rutz. All rights reserved. SwingOSC is released under the GNU General Public License and comes with absolutely no warranties. To contact the author, send an email to contact at sciss.de

For project status, API and current version, visit www.sciss.de/swingOSC.

For OSC communication, SwingOSC uses the NetUtil library, which is licensed under the GNU Lesser General Public License (LGPL). The compiled library is included, for sourcecode and details visit www.sciss.de/netutil.

security note

SwingOSC uses UDP and TCP network protocols. It allows to create and execute almost any kind of java code on your machine. Therefore, running SwingOSC in a network that can be accessed from outside is a severe security problem, allowing hijacking, information retrieval and massive damage on your machine. You have been warned!

It is strongly advised to launch SwingOSC with the -L option which limits communication to the local computer. Alternatively, make sure your firewall settings are appropriate.

download

The current version can be downloaded here:

• sourceforge.net/projects/swingosc

The SuperCollider for Windows built maintained by the IEM Graz already comes with a preconfigured SwingOSC installation (however not always the newest):

• sourceforge.net/project/showfiles.php?group_id=54622&package_id=133499

Developers can download the lastest version from Subversion (SVN):

> cd <baseDir>
> svn co https://swingosc.svn.sourceforge.net/svnroot/swingosc/trunk/ SwingOSC

The subversion download comes in source form and needs to be compiled (see the compilation section below). The regular download already includes a precompiled binary.

requirements / installation

SwingOSC is written in Java(tm) and requires a Java runtime environment (JRE) version 1.4 or better. On Mac OS X you already have this runtime. On other platforms you may need to download and install a recent runtime from java.sun.com. You can verify your current java version by opening a terminal and executing the command java -version.

Linux note: There are other free implementations for the Java standard platform, like Apache Harmony and GNU Classpath. Kaffe.org has a list of related things. I have tested SwingOSC only with Sun's and Apple's VM and I don't know whether it runs with those alternatives. Particularly AWT (the GUI base system) is incomplete, so I don't recommend using for example gij which seems to be the default on Debian / Ubuntu. Installing Sun's Java does not imply that you cannot have your current alternative Java installed (see nescivi's posting on this thread for details: www.nabble.com/swingOSC-installation-on-Linux-Ubuntu-7.04-t4638827.html).

• Installing SuperCollider classes : please refer to the separate file SuperCollider/readme.html
• Double-click launcher on Mac OS X : you can use the files SwingOSC_TCP.command and SwingOSC_UDP.command to boot a standard server. As of v0.29 they can be executed out-of-the-box. However, you may wish to customize the SwingOSC options using a text editor such as the TextEdit application. If you cannot double-click these files, select each in the Finder and open the information window (Cmd+I). Choose to open these documents with the Terminal application (located in /Applications/Utilities).

To use MovieView.java (i.e. JSCMovieView), you will need the Java Media Framework (JMF) classes from Sun (on Mac OS X use the cross-platform download). Put jmf.jar in your system's classpath, e.g. on Mac OS X that can be /Library/Java/Extensions. I'm hoping to find a better solution for movie playback in the future.

launching the server

Open a terminal and cd into the SwingOSC folder. Either run the default script by typing sh SwingOSC.sh, or launch with custom options:

   > java [java-VM-options] -jar build/SwingOSC.jar [swing-osc-options]

where the VM options are:

• -Dswing.defaultlaf=<LookAndFeelClassName> : specify a custom look-and-feel class. e.g. com.birosoft.liquid.LiquidLookAndFeel.
• -Dapple.awt.brushMetalLook=true : (Mac OS only) use the brushed-metal window skin as known from the Finder and traditional SuperCollider GUI.
• -Xdock:icon=application.icns : (Mac OS only) use a prettier icon for display in the dock and programme switching screen.
• -Xdock:name=SwingOSC : (Mac OS only) alternative screen name

and the SwingOSC options are:

• -t <port> : use the given TCP port for message reception. The SuperCollider classes assume that you use port 57111!
• -u <port> : use the given UDP port for message reception. if absent, an arbitrary free port will be picked.
• -L : use loopback address ("127.0.0.1") for communication. if absent, the local host's IP address is used. when your computer is connected to a network and SwingOSC needs only be accessed from the local computer, make sure you use this option to minimize the security issue mentioned above.
• -i : run Swing initialization upon startup. On Mac OS, a terminal app becomes a GUI app with screen menu bar and icon in the Dock, as soon as an AWT or Swing component is created. This initialization can be enforced by using this opton.
• -h <host:port> : send a [ /swing, "hello", <swingHost>, <swingPort>, <swingProtocol> ] message to the given UDP socket. this kind of manual "bonjour" is used by the SuperCollider classes to detect the startup of the SwingOSC server.

if you wish to include custom java classes or libraries, you can either

• use the /classes OSC command (see OSC reference for details).
• or include them in the SwingOSC.jar file, add them to the java class path, as shown in the following example which adds the freetts speech libraries (assuming they have been copied to the lib folder):

     > java -cp build/SwingOSC.jar:lib/freetts.jar:lib/jsapi.jar de.sciss.swingosc.SwingOSC [swing-osc-options]

documentation / usage

Please read the DevelopersNeeded note.

• A few example for SuperCollider and Pure Data are included in their respective examples folders.
• The file OSC-Command-Reference.html provides an introduction to the concept of SwingOSC and explains all commands that the server understands.
• API documentation is not yet generated. However some of the java classes contain already javadoc comments, so it should be quite easy to get started.

compilation

The source code can be compiled using Eclipse SDK 3.2+ (www.eclipse.org) and Apache Ant 1.6.5+ (ant.apache.org). You need to install Ant-Contrib as well (first install Ant if you do not have it, then download Ant-Contrib and copy ant-contrib.jar into Ant's lib folder). The Eclipse project file is configured to run the regular Ant build file. You can make a clean build just with Ant from the terminal:

> ant clean jar
> ant test

The "test" will just launch SwingOSC so you can see if the build works; you can leave away that task. By default, NetUtil is included in the resulting file build/SwingOSC.jar. If wish to link externally to it, you can build like this:

> ant -Dplain=true clean jar

To compile MovieView.java, you will need to have jmf.jar in your classpath (see requirements sections above). If JMF is not installed, the Ant build will skip the compilation of MovieView.java and you will not be able to use JSCMovieView.

known issues

• in TCP mode SuperCollider on Mac OS X often crashes when the server quits.
• with a lot of messages sent en-bloc from sclang – and even a sparsely populated window setup means a lot of OSC traffic –, there can be a buffer overflow which results in the last messages being lost when using UDP transport. as a circumvention, you can either
  • use TCP mode
  • or put your GUI buidling process in a Routine and place short wait statements in the body until no more message dropping occurs.

to-do list

• password protection in TCP mode?
• text file or similar with a restriction list of allowed classes to instantiate?
• complete peakmeterview, add some nice stuff like tree view ...

change history

v0.59 (feb 2008 - SVN rev. 56)

• sc classes: JavaObject (added double underscore syntax, calling prRemove from JSCPlug(Container)View), SwingOSC (separate java field, faster booting, bootSync fix), SwingOptions (javaOptions field), SwingGUI (updated), JSCMultiSlider (valueAction_ fix), JSCPopUpMenu (value_ fix), JSCListView (value_ fix), JKnob (was broken), removed JEZSlider, JEZNumber.
• java classes: DummyTransferHandler sends file-lists

v0.58 (jan 2008 - SVN rev. 47)

• sc classes: SwingOSC (aliveThread has longer timeout, improved isLocal detection), JavaObject (added print, isNull, notNull methods), extSwingOSC (fixed asSwingArg implementations, removed jinspect, jplot, jmakeWindow, jscope, jbrowse)
• sc gui classes: JSCWindow (added resizable_, redefined drawHook refresh policy, cocoa-bounds translation look-and-feel independant, added scroll argument to contructor), JSCNumberBox (drag'n'drop fixed), JSCTextField (drag'n'drop fixed), JSCUserView (added mousePosition, clearOnRefresh_ methods), JSCPlug(Container)View (improved doesNotUnderstand), JSCView (proper layout manager validation with bounds_ and visible_, added addAction and removeAction methods), SwingGUI (added tabletView, scrollView), extCocoaCompat (removed methods that have been added to the standard library), JSCTextView (fixed property changes when document is empty), removed JSCScrollPane, JStartRow, added JSCScrollView, JSCScrollTopView, JSCTabletView
• sc helper classes improvements: Collapse (function call error protection), Insets (added leftTop method), added UpdateListener
• sc help files: completed, partly reformatted
• java classes: SwingOSC (fixed checkMethodArgs type priorities)
• java gui classes: ActionResponder (bug fix), WindowResponder (bounds-to-cocoa translation), ColliderLayout (to work with scrollview), MouseResponder and ComponentResponder (to work with relativeOrigin parents), ContentPane (extracted from Frame), DummyTransferHandler (preserve clipboard cut/copy/paste actions), Frame (scroll support, cocoa-bounds translation, setAlpha method), NumberField (String based setNumber method to avoid roundoff errors), Pen (fixed stroke shape transform when shearing, support for relativeOrigin, bug fixes), RangeSlider (more pretty knob scaling)
• java helper classes: AudioFile (added retrieveType method)

v0.56 (oct 2007)

• sc and java classes: bug fixes (alpha tranparency, FlowView support)

v0.55 (sep 2007)

• added tutorial from the den haag symposium
• sc classes: bug fixes, enhancements in JavaObject
• java classes: updates and compatibility with Forest/Timebased project

v0.54 (jul 2007)

• osc commands: added remove and update commands to "/classes"
• sc classes: added JSCScrollBar, updated SwingGUI, SwingOSC, caching option for JSCSoundFileView, curve shapes for JSCEnvelopeView

v0.53 (jul 2007)

• updated NetUtil, assuring UTF-8 string encoding
• fixed -h option
• sc classes: updated SwingGUI, crucial support, various fixes

v0.52 (apr 2007)

• bug fixes: JSCWindow-bounds
• new classes: JKeyState, JStartRow, SwingGUI
• help files converted to HTML (c. 2/3 still need proper clean-up though)

v0.513 (apr 2007)

• fixes a number of known issues (JSCView.bounds_, JSCEnvelopeView.value_, JSCPopUpMenu.item_, JSCListView.item_)

v0.51 (mar 2007)

• includes NetUtil 0.32 (= fixes umlaut problems)
• using Apache Ant now for building
• removed non-breaking-spaces from help files (= avoids PsyCollider bug)
• bug fixes in SC classes: continuous text/number updates while typing in JSCTextField, JSCNumberBox ; graphics glitches with JSCSoundFileView and JSCEnvelopeView on Linux/Windows ; bounds updates when parent views move

v0.50 (feb 2007)

• java classes: fixed opacity and background colour issues. added layout managers for supercollider, added AbstractMultiSlider, EnvelopeView, TextView, DocumentResponder, ActionMessenger. lot's of fixes and improvement (MovieView, RangeSlider, SoundFileView, Pen, MouseResponder, Frame)
• sc classes: added JSCEnvelopeView, finished JSCTextView, fixed JSCCompositeView, JSCHLayoutView, JSCVLayoutView, added support for elastic views. Dozens of fixes and improvements (JPen, JSlider, JRangeSlider, JSCSoundFileView, JSCMovieView, JSCWindow, JFont, JEZSlider, JEZNumber, probably others)
• .sh shell scripts now specify Gtk+ look-and-feel. Edit them if you want to return to metal look-and-feel.

v0.44 (dec 2006)

• new sc classes: JSCSoundFileView, JSCMovieView, JSCTabbedPane, JSCCheckBox
• fixes: JFont, JSCTextField, JPen

v0.43 (oct 2006)

• sc classes: JSCMultiSliderView

v0.42 (oct 2006)

• adds dynamic class loading and /classes OSC command
• uses updated NetUtil, and hence has TCP server mode (TCP is default now)
• renamed OSCClient.java to SwingClient.java
• sc classes: fixes (keyboard actions in JSC2DSlider, opacity in JSCCompositeView, focus in JSCSlider), missing classes (SwingDialog), modifications (string operations in JPen)
• error messages are printed to System.out not System.err, so they are visible in SuperCollider's post window
• v0.421 makes new() and start() in SwingOSC.java public (e.g. to be accessible by Eisenkraut)

v0.41 (aug 2006)

• fixes for JSCCompositeView, completions for JSCWindow
• includes JSCPlugView, JSCPlugContainerView, JavaObject

v0.40 (apr 2006)

• OSC syntax change: using nested blob'ed OSC messages is deprecated ; instead nesting is achieved by using special string arguments. this makes SwingOSC really usable in other clients such as Pure Data.
• added first examples for Pure Data
• sc classes: all modified to use the new OSC syntax. added JPen, JSCUserView, JSCTextView, fixed JSCHLayoutView and JSCVLayoutView, added mouse, component resize and focus traversal tracking, modified the JMouseBase gui, optimized performance, fixed a lot of bugs.
• MultiStateButton was moved to the de.sciss.gui package and is slightly modified.

v0.39 (mar 2006)

• sc classes: SwingOSC.sc : booting now works. Help file updated

v0.38 (feb 2006)

• sc classes: finished JStethoscope / JSCScope / .jscope plusGUI
• sc classes: converted FreqScope by Lance Putnam
• added -h option

v0.37 (feb 2006)

• cleanup and slight performance improvisation
• added /field and /fieldr commands
• messages whose arguments contain nested messages are evaluated strictly sequentially, making side effects much more stringent
• bug fixes: /free
• removed "toolkit" object assignment which caused the -i option to be ineffective. you can restore the original binding by sending a message [ "/local", \toolkit, [ "/method", "java.awt.Toolkit", \getDefaultToolkit ]]

v0.36 (dec 2005)

• added JSCDragSource/Sink/Both supercollider classes
• added keyboard + drag'n'drop support in supercollider classes
• optimization and fixes in supercollider classes

v0.35 (dec 2005)

• switched to Eclipse for development
• added RangeSlider and Slider2D classes (+ related SC classes)
• added JMacUGens.sc supercollider class
• added /import package lookup mechanism (not yet accessible though)

v0.3 (nov 2005)

• reworked (new) OSC command structure
• prelimary SC classes

v0.2 (aug 2005)

• includes example of the possibility to instantiate applets (nice for integrating Proce55ing)

java is a trademark of sun microsystems
i think mac os and xcode are trademarks of apple inc
windows is one of microsoft corp
jever is a trademark of some west german beer factory